﻿<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>GoJS Grid Patterns -- Northwoods Software</title>
  <!-- Copyright 1998-2020 by Northwoods Software Corporation. -->
  <script src="../release/go.js"></script>
  <script src="goIntro.js"></script>
</head>
<body onload="goIntro()">
<div id="container" class="container-fluid">
<div id="content">

<h1>Grid Patterns</h1>
<p>
It is common to want to display a grid of lines drawn at regular intervals.
You may also want to force dragged parts to be aligned on grid points, and to resize parts to be multiples of the grid cell size.
</p>
<p>
Grids are implemented using a type of <a>Panel</a>, <a>Panel,Grid</a>.
Grid Panels, like most other types of Panels, can be used within <a>Node</a>s or any other kind of <a>Part</a>.
However when they are used as the <a>Diagram.grid</a>, they are effectively infinite in extent.
</p>
<p>
Unlike in other kinds of <a>Panel</a>s, Grid Panel elements must be <a>Shape</a>s that are only used to control how the grid lines or grid bars are drawn.
</p>
<p>
See samples that make use of grids in the <a href="../samples/index.html#grid">samples index</a>.
</p>

<h2 id="DefaultGrid">Default Grid</h2>
<p>
To display a grid pattern in the background of the diagram, you can just make the <a>Diagram.grid</a> visible:
</p>
<pre class="lang-js" id="defaultGrid">
  diagram.grid.visible = true;

  diagram.nodeTemplate =
    $(go.Node, "Auto",
      $(go.Shape, "Rectangle", { fill: "lightgray" }),
      $(go.TextBlock, { margin: 5},
        new go.Binding("text", "key"))
    );
  var nodeDataArray = [
    { key: "Alpha" }, { key: "Beta" }, { key: "Gamma" }
  ];
  diagram.model = new go.GraphLinksModel(nodeDataArray);
</pre>
<script>goCode("defaultGrid", 600, 150)</script>

<h2 id="GridSnapping">Grid Snapping</h2>
<p>
The <a>DraggingTool</a> and <a>ResizingTool</a> can change their behavior based on the background grid pattern,
if you set the <a>DraggingTool.isGridSnapEnabled</a> and/or <a>ResizingTool.isGridSnapEnabled</a> properties to true.
</p>
<p>
  Setting <a>DraggingTool.isGridSnapEnabled</a> to true will not affect disconnected Links,
  but these can snap if you define a custom <a>Part.dragComputation</a> to do so on the Link template.
</p>
<pre class="lang-js" id="gridSnapping">
  diagram.grid.visible = true;
  diagram.toolManager.draggingTool.isGridSnapEnabled = true;
  diagram.toolManager.resizingTool.isGridSnapEnabled = true;


  diagram.nodeTemplate =
    $(go.Node, "Auto",
      { resizable: true },
      $(go.Shape, "Rectangle", { fill: "lightgray" }),
      $(go.TextBlock, { margin: 5},
        new go.Binding("text", "key"))
    );
  var nodeDataArray = [
    { key: "Alpha" }, { key: "Beta" }, { key: "Gamma" }
  ];
  diagram.model = new go.GraphLinksModel(nodeDataArray);
</pre>
<script>goCode("gridSnapping", 600, 150)</script>

<h2 id="SimpleGridCustomization">Simple Grid Customization</h2>
<p>
You can change the size of the grid cell by setting <a>Panel.gridCellSize</a>:
</p>
<pre class="lang-js" id="biggerGrid">
  diagram.grid.visible = true;
  diagram.grid.gridCellSize = new go.Size(30, 20);
  diagram.toolManager.draggingTool.isGridSnapEnabled = true;
  diagram.toolManager.resizingTool.isGridSnapEnabled = true;


  diagram.nodeTemplate =
    $(go.Node, "Auto",
      { resizable: true },
      $(go.Shape, "Rectangle", { fill: "lightgray" }),
      $(go.TextBlock, { margin: 5},
        new go.Binding("text", "key"))
    );
  var nodeDataArray = [
    { key: "Alpha" }, { key: "Beta" }, { key: "Gamma" }
  ];
  diagram.model = new go.GraphLinksModel(nodeDataArray);
</pre>
<script>goCode("biggerGrid", 600, 150)</script>

<p>
The cell size used when snapping the locations of Parts during a drag need not be exactly
the same as the background grid's cell size.
The value of <a>DraggingTool.gridSnapCellSize</a> takes precedence over the <a>Panel.gridCellSize</a>.
Note that if <a>DraggingTool.gridSnapCellSize</a> is set but <a>ResizingTool.cellSize</a> is not,
Parts will use the DraggingTool.gridSnapCellSize value when resizing.
</p>
<pre class="lang-js" id="gridSnapping2">
  diagram.grid.visible = true;
  diagram.toolManager.draggingTool.isGridSnapEnabled = true;
  diagram.toolManager.resizingTool.isGridSnapEnabled = true;

  // snap to every other point both vertically and horizontally
  // (the default background grid has a cell size of 10x10)
  diagram.toolManager.draggingTool.gridSnapCellSize = new go.Size(20, 20);


  diagram.nodeTemplate =
    $(go.Node, "Auto",
      { resizable: true },
      $(go.Shape, "Rectangle", { fill: "lightgray" }),
      $(go.TextBlock, { margin: 5},
        new go.Binding("text", "key"))
    );
  var nodeDataArray = [
    { key: "Alpha" }, { key: "Beta" }, { key: "Gamma" }
  ];
  diagram.model = new go.GraphLinksModel(nodeDataArray);
</pre>
<script>goCode("gridSnapping2", 600, 150)</script>

<h2 id="CustomGrids">Custom Grids</h2>
<p>
Grid patterns are implemented by the <a>Panel</a> class when its <a>Panel.type</a> is <a>Panel,Grid</a>.
The elements of a Grid Panel must be <a>Shape</a>s whose <a>Shape.figure</a> is one of a small set of known kinds of figures.
The only figures it can accept are: "LineH", "LineV", "BarH", and "BarV".
The two "Line" figures result in stroked lines separating the grid cells;
the two "Bar" figures result in filled rectangles in the grid cells.
</p>
<p>
Here is a simple grid consisting of blue horizontal lines and green vertical lines:
</p>
<pre class="lang-js" id="customBackground">
  diagram.grid =
    $(go.Panel, go.Panel.Grid,  // or "Grid"
      { gridCellSize: new go.Size(25, 25) },
      $(go.Shape, "LineH", { stroke: "blue" }),
      $(go.Shape, "LineV", { stroke: "green" })
    );
</pre>
<script>goCode("customBackground", 600, 150)</script>

<p>
The <a>Shape.interval</a> property is also used by a Grid Panel to determine how frequently a line should be drawn.
The value should be a positive integer specifying how many cells there are between drawings of this particular line.
So if you wanted darker blue and darker green lines every five cells:
</p>
<pre class="lang-js" id="customBackground2">
  diagram.grid =
    $(go.Panel, "Grid",
      { gridCellSize: new go.Size(10, 10) },
      $(go.Shape, "LineH", { stroke: "lightblue" }),
      $(go.Shape, "LineV", { stroke: "lightgreen" }),
      $(go.Shape, "LineH", { stroke: "blue", interval: 5 }),
      $(go.Shape, "LineV", { stroke: "green", interval: 5 })
      );


  diagram.nodeTemplate =
    $(go.Node, "Auto",
      { resizable: true },
      $(go.Shape, "Rectangle", { fill: "lightgray" }),
      $(go.TextBlock, { margin: 5},
        new go.Binding("text", "key"))
    );
  var nodeDataArray = [
    { key: "Alpha" }
  ];
  diagram.model = new go.GraphLinksModel(nodeDataArray);
</pre>
<script>goCode("customBackground2", 600, 150)</script>
<p>
Note that the Shapes are drawn in the order in which they appear in the Panel,
so you can see that the dark blue horizontal lines are drawn in front of the light green vertical lines,
and that the dark green vertical line crosses in front of the dark blue horizontal lines.
</p>
<p>
Here is the definition of the predefined <a>Diagram.grid</a>:
</p>
  <pre class="lang-js" id="standardGrid">
  diagram.grid =
    $(go.Panel, "Grid",
      {
        name: "GRID",
        visible: false,
        gridCellSize: new go.Size(10, 10),
        gridOrigin: new go.Point(0, 0)
      },
      $(go.Shape, "LineH", { stroke: "lightgray", strokeWidth: 0.5, interval: 1 }),
      $(go.Shape, "LineH", { stroke: "gray", strokeWidth: 0.5, interval: 5 }),
      $(go.Shape, "LineH", { stroke: "gray", strokeWidth: 1.0, interval: 10 }),
      $(go.Shape, "LineV", { stroke: "lightgray", strokeWidth: 0.5, interval: 1 }),
      $(go.Shape, "LineV", { stroke: "gray", strokeWidth: 0.5, interval: 5 }),
      $(go.Shape, "LineV", { stroke: "gray", strokeWidth: 1.0, interval: 10 })
    );

  diagram.grid.visible = true;  // so that this example shows the standard grid
  diagram.div.style.background = "white";
</pre>
<script>goCode("standardGrid", 600, 150)</script>
<p>
You can get a green-bar pattern by using the "BarH" figure.  Note the use of <a>Shape.fill</a>
instead of <a>Shape.stroke</a> and explicitly setting the <a>GraphObject.height</a>:
</p>
<pre class="lang-js" id="customBackground3">
  diagram.grid =
    $(go.Panel, "Grid",
      { gridCellSize: new go.Size(50, 50) },
      $(go.Shape, "BarH", { fill: "lightgreen", interval: 2, height: 50 })
      );


  diagram.nodeTemplate =
    $(go.Node, "Auto",
      {
        dragComputation: function(node, pt, gridpt) {
          pt.y = Math.round(pt.y/100)*100;
          return pt;
        }
      },
      $(go.Shape, "Rectangle", { fill: "lightgray" }),
      $(go.TextBlock, { margin: 5},
        new go.Binding("text", "key"))
    );
  var nodeDataArray = [
    { key: "Alpha" }
  ];
  diagram.model = new go.GraphLinksModel(nodeDataArray);
</pre>
<script>goCode("customBackground3", 600, 350)</script>
<p>
This example also demonstrates how one can use the <a>Part.dragComputation</a> property to customize where
the user can drag the node.  In this case the <a>Part.location</a>.y is limited to be multiples of 100,
corresponding to the rows of cells filled by the green bars.
</p>
<p>
To get a tablecloth effect, one can use both vertical and horizontal bars with a translucent color:
</p>
<pre class="lang-js" id="customBackground4">
  diagram.grid =
    $(go.Panel, "Grid",
      { gridCellSize: new go.Size(100, 100) },
      $(go.Shape, "BarV", { fill: "rgba(255,0,0,0.1)", width: 50 }),
      $(go.Shape, "BarH", { fill: "rgba(255,0,0,0.1)", height: 50 })
      );

  diagram.toolManager.draggingTool.isGridSnapEnabled = true;

  diagram.nodeTemplate =
    $(go.Node, "Auto",
      { width: 50, height: 50 },
      $(go.Shape, "Rectangle", { fill: "lightgray" }),
      $(go.TextBlock, { margin: 5},
        new go.Binding("text", "key"))
    );
  var nodeDataArray = [
    { key: "Alpha" }
  ];
  diagram.model = new go.GraphLinksModel(nodeDataArray);
</pre>
<script>goCode("customBackground4", 600, 350)</script>
<p>
This example limits dragging of all nodes by setting <a>DraggingTool.isGridSnapEnabled</a> to true.
</p>
<p>
Here is an example of using a "Grid" <a>Panel</a> as a regular data bound element in a <a>Node</a>:
</p>
<pre class="lang-js" id="nodeGrid">

  diagram.nodeTemplate =
    $(go.Node, "Auto",
      { resizable: true, resizeObjectName: "GRID" },
      $(go.Shape, "Rectangle", { fill: "transparent" }),
      $(go.Panel, "Grid",
        { name: "GRID", desiredSize: new go.Size(100, 100), gridCellSize: new go.Size(20, 20) },
        new go.Binding("desiredSize", "size", go.Size.parse).makeTwoWay(go.Size.stringify),
        new go.Binding("gridCellSize", "cell", go.Size.parse).makeTwoWay(go.Size.stringify),
        $(go.Shape, "LineV",
          new go.Binding("stroke")),
        $(go.Shape, "LineH",
          new go.Binding("stroke"))
      ));

  diagram.model = new go.GraphLinksModel([
    { key: "Alpha", cell: "25 25", stroke: "lightgreen" },
    { key: "Beta", size: "150 75", cell: "15 30" }
  ]);
</pre>
<script>goCode("nodeGrid", 600, 350)</script>

<h2 id="OtherConsiderations">Other Considerations</h2>
<p>
  A Grid Panel should have a non-null <code>background</code> if it needs to be pickable.
  One cannot set or bind the <a>Panel.itemArray</a> of a Grid Panel.
</p>
<p>
  Events on the Shapes will be ignored.
  Shapes in a Grid Panel must not be scaled or rotated.
</p>

</div>
</div>
</body>
</html>
